Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOModel

Inherits From:	NSObject

Declared In:	eoaccess/EOModel.h

Class Description

An EOModel holds the mapping between a database schema and the object classes representing that database in an application. An EOModel contains a number of EOEntity objects representing the entities (tables) of the database schema. Each EOEntity object has a set of EOAttributes for the properties (columns or fields) of the entity in the database schema, and EORelationships joining entities through their attributes. See these class specifications for more detailed information on models.

An EOModel maintains a mapping between each of its EOEntity objects and a corresponding enterprise object class for use with the database level of the Enterprise Objects Framework. You can determine the EOEntity for a particular enterprise object with the entityForObject: method. To get the enterprise object class for an entity, you use EOEntity's className method.

An EOModel stores the information needed to connect to its database server as well as the name of an adaptor bundle to load so that the Enterprise Objects Framework can communicate with the database. Models are stored in the file system in a manner similar to adaptor bundles; see ªLoading a Model Fileº below for more information.

Like the other major modeling classes, EOModel provides a user dictionary for the application to store any auxiliary information it needs.

Loading a Model File

EOModels are usually loaded from model files built with the EOModeler application rather than built programmatically. Model files stored in the standard resource directory search path: the application's main bundle, ~/Library/Models, /LocalLibrary/Models, and /NextLibrary/Models. EOModel's findPathForModelNamed: class method searches this path for the base filename of a model and returns the full path of the requested file. Once you have this path you simply use initWithContentsOfFile: to load your model. This code excerpt shows how you would load a model file named People.eomodel:

NSString *modelPath;
EOModel *peopleModel;

modelPath = [EOModel findPathForModelNamed:@"People"];
peopleModel = [[EOModel alloc] initWithContentsOfFile:modelPath];

Creating an EOModel Programmatically

The EOAdaptorChannel class declares methods for reading basic schema information from a relational database. You can use this information to build up an EOModel programmatically, and then enhance that model by defining extra relationships, flattening attributes, and so on. See the class description in the EOAdaptorChannel class specification for information on reading basic schema information, and see the other modeling classes' specifications for information on creating additional attributes and relationships.

Instance Variables

None declared in this class.

Method Types

Searching for a model file	+ findPathForModelNamed:

Initializing instances	- initWithContentsOfFile:
- initWithPropertyList:
- initWithName:

Getting the filename	- path

Getting a property list representation
- modelAsPropertyList

Getting the name	- name

Using entities	- addEntity:
- removeEntityNamed:
- entityNamed:
- entities

Checking references	- referencesToProperty:

Getting an object's entity	- entityForObject:

Adding model information	- incorporateModel:

Setting the adaptor bundle	- setAdaptorName:
- adaptorName

Setting the connection dictionary
- setConnectionDictionary:
- connectionDictionary

Setting the user dictionary	- setUserDictionary:
- userDictionary

Class Methods

findPathForModelNamed:

+ (NSString *)findPathForModelNamed:(NSString *)name

Returns the full (absolute) path for the model file whose base filename is name, or nil if it can't be found. Searches the application's main bundle, ~/Library/Models, /LocalLibrary/Models, and /NextLibrary/Models, in that order. The returned name is suitable for use in an initWithContentsOfFile: message.

Instance Methods

adaptorName

- (NSString *)adaptorName

Returns the name of the adaptor for the model. This name can be used with EOAdaptor's adaptorWithName: class method to create an adaptor.

addEntity:

- (BOOL)addEntity:(EOEntity *)anEntity

Adds anEntity to the model. Returns YES if successful, NO if an entity with the same name already exists in the model.

See also:  - removeEntityNamed:

connectionDictionary

- (NSDictionary *)connectionDictionary

Returns a dictionary containing information used to connect to the database server. The connection dictionary is a convenient place to specify default login information for applications using the model. See the EOAdaptor class specification for more information.

entities

- (NSArray *)entities

Returns an array containing the EOModel's entities.

entityForObject:

- (EOEntity *)entityForObject:anEO

Returns the entity associated with anEO, whether anEO is an instance of an enterprise object class, an instance of EOGenericRecord, or a fault object (see the EOFault class specification for information on faults). Returns nil if anEO has no associated entity.

entityNamed:

- (EOEntity *)entityNamed:(NSString *)name

Returns the entity named name, or nil if no such entity exists.

incorporateModel:

- (BOOL)incorporateModel:(EOModel *)aModel

Copies the contents of aModel into the receiver. Returns YES if successful, NO if any identically named elements of the two models differ, or if the two models use different adaptors. Doesn't affect the connection dictionary of the receiver.

You can use this method to merge subsets of a larger model as they're loaded from individual resources, such as nib files.

	Warning:	This method assumes ownership of and disposes of aModel. If you want to keep a model that you incorporated into another, you should create a fully independent copy and incorporate that:

modelCopy = [[EOModel alloc]
    initWithPropertyList:[modelToIncorp modelAsPropertyList]];
[myModel incorporateModel:modelCopy];

See also:  - setConnectionDictionary:

initWithContentsOfFile:

- initWithContentsOfFile:(NSString *)path

Initializes a newly allocated EOModel by reading the contents of the file named path as a property list representation with initWithPropertyList:. path must contain the full name of the model file, including the .eomodel extension.

See also:  + findPathForModelNamed:, - path

initWithName:

- initWithName:(NSString *)name

Initializes a newly allocated EOModel with name as its name. The EOModel needs to have entities with attributes before it's usable. This is the designated initializer for the EOModel class. Returns self.

initWithPropertyList:

- initWithPropertyList:aPropertyList

Initializes a newly allocated EOModel from aPropertyList, which is a property list representation created by sending modelAsPropertyList to an existing model. Property list representations are used to save models to and load them from files. initWithContentsOfFile: is roughly equivalent to this code excerpt:

NSString *path;   /* Assume this exists. */
NSString *aPropertyList;
EOModel *myModel;

aPropertyList = [[[NSString alloc] initWithContentsOfFile:path]
    autorelease];
myModel = [[EOModel alloc] initWithPropertyList:aPropertyList];

modelAsPropertyList

- modelAsPropertyList

Returns a string object encoding the EOModel as an ASCII property list. This representation can be saved to a file and later reloaded using initWithContentsOfFile:. The following code excerpt saves an EOModel to a file named People.eomodel:

EOModel *myModel;    /* Assume this exists. */
NSString *aPropertyList;

aPropertyList = [myModel modelAsPropertyList];
[aPropertyList writeToFile:@"People.eomodel" atomically:YES];

See also:  - initWithPropertyList:

name

- (NSString *)name

Returns the model's name.

path

- (NSString *)path

Returns the full path of the model file used to create the EOModel (including the .eomodel extension), or nil if the model wasn't initialized from a file.

referencesToProperty:

- (NSArray *)referencesToProperty:aProperty

Returns an array of all properties in the model that reference aProperty: derived attributes, relationships that reference aProperty, and so on. aProperty itself may be either an EOAttribute or an EORelationship.

removeEntityNamed:

- (void)removeEntityNamed:(NSString *)name

Removes the EOEntity named name from the model. Raises NSInvalidArgumentException is there is no such entity.

See also:  - addEntity:

setAdaptorName:

- (void)setAdaptorName:(NSString *)adaptorName

Sets the name of the model's adaptor to adaptorName.

setConnectionDictionary:

- (void)setConnectionDictionary:(NSDictionary *)aDictionary

Sets the dictionary containing information used to connect to the database to aDictionary. Note that if the adaptor has already been initialized with the model, this method does not propagate the connectionary down to the adaptor. See the EOAdaptor class specification for more information on working with setConnectionDictionary:.

setUserDictionary:

- (void)setUserDictionary:(NSDictionary *)aDictionary

Sets the dictionary of auxiliary data, which your application can use for whatever it needs. This dictionary must be a property list (that is, it must contain only NSString, NSData, NSArray, and NSDictionary objects).

userDictionary

- (NSDictionary *)userDictionary

Returns a dictionary of user data. Your application can use this to store any auxiliary information it needs. This dictionary is a property list (that is, it contains only NSString, NSData, NSArray, and NSDictionary objects).